NB-Assets Tutorial

NB-Asset is a simple asset management tool for IPython Notebook extensions. Other web asset management solutions cater to the needs of websites: Few http requests, small filesize, serving files through S3 or NGINX and so on. These concerns don't matter as much in the notebook interface.

Features and Goals:

simple description of source files in code
source map generation
ability to reload code files on the same page
loading files from library directories

Using javascript/coffeescript files in a notebook

Loading and using javascript and coffeescript files in the notebook is easy:



In [1]:

    
import nb_assets



In [2]:

    
assets =  [("coffeescript", "test.coffee"),
           ("javascript", "hello_javascript.js")]
nb_assets.display_assets(assets, input_dir="assets", output_dir="static")

The tuples in the assets list refer to a recipe and a source files. Recipes compile and load the asset into the page. Currently only coffeescript and javascript are available.

"input_dir" refers to the source directory, and "output_dir" refers to the output directory, in this case as path names relative to the notebook file.

The coffeescript files are only compiled if they have changed since the last compilation. This allows for efficient development, but it also means that other developers don't need a coffeescript compiler as long as they don't change the coffeescript source code.

That's important, because in general, IPython Notebook users who use an extension in a python library or download a cool notebook file, aren't guaranteed to have a coffeescript compiler. NB-Assets makes it easy to hide the magic!

Including assets into a library/package

If you wrote a cool widget for a python library, you will probably want to include your assets into the library itself. The easiest way is to have an input directory inside the libraries base directory, and resolve it like so:

assets =  [("coffeescript", "test.coffee"),
           ("javascript", "hello_javascript.js")]
def output_notebook():
    import nb_assets
    base_dir = os.path.dirname(__file__)
    input_dir = os.path.join(os.path.dirname(nb_assets.__file__), 'assets', 'src')
    output_dir = os.path.join(base_dir, 'assets', 'compiled')
    nb_assets.display_assets(assets, input_dir=input_dir, output_dir=output_dir)

Some caveats:

Files are only recompiled if they have been modified more recently than their outputs, but if the cell containing the display_assets call is reexecuted, all files will be reloaded into the page.
If compilation is needed, the output file must be writeable. For distribution packages, make sure the compiled files are current, so that the library doesn't try to recompile them into system directories.
Make sure that your library is importable without ipython, ipython notebook and nb-assets libraries installed and running. One way to do this is to only import nb_assets in the output method. There are other ways, of course.

Coffeescript Cell Magic

There are various implementations of a coffeescript magic floating around the internet, but as far as I know, none in a distributable package. Because such a cell magic is really useful when developing notebook features, NB-assets contains such a cell magic. This implementation does not offer source maps, though.



In [3]:

    
import nb_assets
nb_assets.load_magics()



In [5]:

    
%%coffeescript -vb
console.log "Hello World from Coffeescript magic"
for i in [1..10]
    console.log i









    









  
  
  




// Generated by CoffeeScript 1.8.0
(function() {
  var i, _i;

  console.log("Hello World from Coffeescript magic");

  for (i = _i = 1; _i <= 10; i = ++_i) {
    console.log(i);
  }

}).call(this);



In [ ]: